Fabric CA 用户手册

Hyperledger Fabric CA 就是Fabric的证书颁发机构(CA)。

它做以下这些事:

Fabric CA由一个客户端和一个服务端组成，我们一会讨论。

如果想对Fabric CA贡献你的开发能力, 请参见 Fabric CA 仓库 。

下图展示了Fabric CA在整个架构里的位置。

有两种与fabric-CA server交互的方式: fabric-CA client或fabric SDK 所有和CA服务器的通信都是Rest API REST APIs请查看swagger 文档 fabric-ca/swagger/swagger-fabric-ca.json

上图的右上角展示的是Fabric CA client 或 SDK 连接CA集群的情况。集群前面用HAProxy做负载， 客户端经过负载后连上集群中的一台服务器。

集群中所有的CA服务器都共享了同一个存放着身份信息和证书信息的数据库。 如果配置了LDAP，身份信息就不存在数据库上而是存在LDAP上了。

一台服务器上可能装有多个CA，每个CA可能是根CA或者是中级CA，每个中级CA都有一个上级CA，上级可能是根CA也有可能是另一个中级CA。

在Ubuntu上安装libtool:

在MacOSX上安装libtool:

注解

libtldl-dev is not necessary on MacOSX if you instal libtool via Homebrew

关于libtool的更多信息 https://www.gnu.org/software/libtool.

关于libltdl-dev的更多信息 https://www.gnu.org/software/libtool/manual/html_node/Using-libltdl.html.

安装 fabric-ca-server 和 fabric-ca-client 包到 $GOPATH/bin.

Note: 如果你已经 clone 了 fabric-ca 的repository， 要确保你是在 master branch 上，然后再执行上面这条 ‘go get’ 命令， 否则你会看到如下错误:

用默认配置启动 fabric-ca-server

这个 -b 提供了bootstrap管理员的 enrollment ID 和 secret ; 如果 “ldap.enabled” 设置没设置为true，则这个就必须要提供。

默认的配置文件名为 fabric-ca-server-config.yaml 它默认在本地目录下，但也可以自定义

到这里: https://hub.docker.com/r/hyperledger/fabric-ca/tags/

找到和你的fabric网络兼容的 fabric-ca 版本

到 $GOPATH/src/github.com/hyperledger/fabric-ca/docker/server 目录下打开 docker-compose.yml 文件。

修改 image ，改为你上面找的ca镜像的tag版本。下面这个示例是x86架构的beta镜像。

在 docker-compose.yml 文件路径下，打开命令行 执行如下语句:

这条命令会把镜像拉下来，然后启动fabric-ca服务器

用如下命令编译并启动服务器。

hyperledger/fabric-ca docker 镜像包含了 fabric-ca-server 和 fabric-ca-client。

下面展示了 Fabric CA server 命令的使用

正常结果应该如下:

完成服务端SSL配置后, 下一步是创建一个有权限使用SSL访问数据库的用户， 先登录MySQL 服务器，然后输入如下语句:

mysql> GRANT ALL PRIVILEGES ON . TO ‘ssluser’@’%’ IDENTIFIED BY ‘password’ REQUIRE SSL; mysql> FLUSH PRIVILEGES;

如果你需要指定限制客户端允许的IP，则需将 ‘%’ 改为指定的客户端IP.

MySQL Server - 客户端证书校验配置

安全连接的选项和用于服务器端的选项是相似的 - ssl-ca 识别CA证书，如果用到，必须和服务器端用相同的证书。 - ssl-cert 识别MySQL服务器的证书。 - ssl-key 识别MySQL服务器的私钥。

假设你想要用一个账户来连接，这个账户没有特殊的加密要求或是被一个包括REQUIRE SSL的GRANT statement创建的， 启动MySQL服务至少需要-ssl-cert和-ssl-key选项。然后在服务设置文件中设置 ``db.tls.certfiles``属性并启动CA服务。

为了要求一个客户端证书也是被指定的，创建一个用REQUIRE X509选项的账户。 然后客户端也必须明确客户端密钥和证书文件；否则，MySQL server将会拒绝连接。 为了给CA server指定客户端密钥和证书文件，设置 db.tls.client.certfile``和 ``db.tls.client.keyfile

CA server可以从LDAP server中读取。 特别地，CA server可以和一个LDAP server连接做如下事情： - 认证一个identity去enrollment的优先级 - 检索一个identity用于认证的属性

修改CA server配置文件的LDAP部分来配置CA server连接LDAP服务器

其中:

以下是OpenLDAP server默认配置的样例 OpenLDAP server的docker 镜像文件在 https://github.com/osixia/docker-openldap.

可查看``FABRIC_CA/scripts/run-ldap-tests`` 这个测试脚本，它的测试步骤是： 启动OpenLDAP的docker镜像，然后对它进行配置， 接着运行``FABRIC_CA/cli/server/ldap/ldap_test.go`` 以测试LDAP， 最后停止OpenLDAP服务器。

当LDAP被配置好之后，enrollment过程如下：

当LDAP被配置好之后，提取属性（attribute retrieval）的过程如下：

配置Haproxy去平衡CA server集群中各个server的负载。确保更改hostname和port来对应CA server的设置。

haproxy.conf

注意: 如果要用TLS，需要用 mode tcp.

fabric-ca server默认是一个单独的CA。可以通过 `cafiles`和 `cacount`配置选项来增加其他的CA， 每一个CA都有他自己的home directory。

每个额外的CA将会在他的home directory里生成一个默认的配置文件，其中包括唯一的CA name。 如下命令来启动2个CA：

如果cafiles未使用绝对路径，则CA的home目录将相对于服务器目录存在。

为了使用这个选项，CA配置文件必须已经生成好了，给每个将启动的CA配置好了。 每个配置文件必须有唯一的CA名称，和Common Name（CN），否则服务器会启动失败。 CA配置文件里，每个配置项内容将覆盖默认配置内容，空缺的配置项内容将默认为默认配置的内容。

配置的优先级如下:

一个CA的配置文件至少包括下述内容：

可以设置文档结构如下：

如下命令可以启动两个定制化CA实例：

为了给中级CA创建一个CA签名证书，中级CA必须向父CA登记， 与fabric-ca-client向CA登记申请证书操作一样。 登记需通过用 -u选项指定一个父CA的URL(包含enrollmentID和secret)，下面有示例。 enrollmentID对应的身份属性”hf.IntermediateCA”必须为”true”。 申请到的证书的CN隐性地就是enrollmentID。 如果你显性地指定了CN，将会报错。

其他中级CA 标记请查看 Fabric CA server的配置文件 章节.

Back to Top

这一节讲述如何使用fabric-ca-client的命令。

首先，要先确定Fabric CA client的home目录，其决定顺序如下:

请将配置文件放home目录下后，完成以下过程。

首以下根据需要自定义client home目录下配置文件中的CSR部分，其中``csr.cn``必须设置为bootstrap identity的enrollment ID。 用fabric-ca-client gencsr -csr.cn admin 生成的客户端配置文件中的CSR默认值如下：

请见 CSR fields 查看各配置项的描述.

然后运行 fabric-ca-client enroll 命令去enroll一个identity。例如, 以下命令会enroll一个ID是 admin 密码是 adminpw 的identity， 其调用的是运行在本地的监听7054端口的Fabric CA 服务器。

enroll命令会生成一份enrollment 证书 (ECert), 以及对应的私钥文件和CA根证书 PEM 文件 ，保存在Fabric CA client的 msp 子目录下。 提示信息里会告诉你保存到哪的目录下了。

发起注册请求的身份必须是已经登记（enroll）过的，同时也必须有权限去注册要注册的相应类型的身份。

在register期间，CA server会做两个授权检查:

调用者要register的身份必须是其“hf.Registrar.Roles”属性中所指明的身份中的一个。 例如调用者的“hf.Registrar.Roles”属性值为“peer,app,user”，

那么他不能register orderer类型的identity。

调用者identity的从属关系必须等于要register时候的从属关系的前缀。 例如，一个调用者的从属关系是“a.b”，

那么他可以register一个拥有”a.b.c”的identity， 但不能是“a.c”。

下文的命令用admin identity去register一个新的identity，他的enrollment id是admin2， 类型是user，从属关系是org1.department1，hf.Revoker属性的值为true，foo属性的值为bar。

CA server会返回一个密码，用于这个identity去enroll。 也允许一个管理员去register一个identity， 然后将这个identity对应的enrollment ID和密码给其他人去enroll。

多属性配置如下，可以用逗号隔开，如果属性里有逗号可以双引号括起来。

或

你也可以设置一个默认配置:

下面这条命令只指定了enrollment ID为 “admin3” 其余的属性都来自配置文件，如 type: “user”, affiliation: “org1.department1”, 及两个属性: “hf.Revoker” and “anotherAttrName”.

多属性需要像上面的配置文件那样提供属性名和属性值

如果设置 maxenrollments 为 0 或者不设置则其默认值为 CA的 最大 enrollment 值。 这个注册用户的最大enroll值不能超过CA的最大enroll值， 比如CA的最大值设置为是5，则所有注册的身份只能小于等于 5, 而且也不能设置为 -1 (无限enroll).

下面我们注册一个 peer1 用户，注意这里我们指定了密码，而不是让命令帮我们生成一个默认密码。

注册好身份后就可以enroll，enroll需要使用刚才注册的enrollmentID和密码(比如上节例子里的 password ). 这个enroll和enroll bootstrap身份有点像，只不过我们这里还用到了 “-M” 选项 用于指定生成 MSP (Membership Service Provider) 目录结构。

以下是enroll一个 peer1。 确保 “-M” 指定的目录为你的 peer的 MSP 目录， 要与peer的core.yaml文件里设置的 ‘mspConfigPath’ 值要保持一致。 你也可以设置 FABRIC_CA_CLIENT_HOME 为你的 peer的home目录。

enroll一个orderer也类似，只不过-M指定的是orderer.yaml里的 ‘LocalMSPDir’ 。

一般地，MSP文件夹中的证书文件夹必须包含其他证书认证中心的证书认证链，来代表这个peer是可信的。 以下命令启动了另一个CA server，这个代表完全分开的一个根信任，并且被区块链中的不同成员管理。

以下命令将安装CA2的证书链到peer1的MSP文件夹中：

假设你的证书到期了，就需要用以下命令重新enroll一份了

撤销一个identity会撤销他的所有证书，并阻止他再得到新的证书，撤销一个证书只是使一个证书无效。 撤销者的从属关系是orgs.org1可以撤销从属关系是orgs.org1和orgs.org1.department1的identity，但不能撤销orgs.org1的identity。

命令如下：

例子：bootstrap admin这个超级用户可以撤销**peer1**这个身份

一个属于某个identity的证书可以通过指定他的AKI（Authority Key Identifier）和序列号来撤销:

例如，可以用openssl 命令来得到AKI和序列号，然后将他们传入revoke命令来撤销证书：

这一节讲如何给 Fabric CA client配置TLS

以下是 ``fabric-ca-client-config.yaml``的内容

**certfiles**选项指定被客户端信任的根证书，即CA的根证书，在CA 服务器的home 目录下的ca-cert.pem里。

**client**选项只有在server中配置了相同的TLS配置才用得到（大吉注：即双向认证）。

如果服务器上跑了多个CA，如果未指定CA名，则将会访问到fabric-ca 服务上的默认CA。 CA名可以按如下方式指定:

Back to Top